Skip to content

feat(server)!: implement recursive control condition trees#115

Merged
lan17 merged 39 commits intomainfrom
codex/feature/sc-58429-condition-trees
Mar 17, 2026
Merged

feat(server)!: implement recursive control condition trees#115
lan17 merged 39 commits intomainfrom
codex/feature/sc-58429-condition-trees

Conversation

@lan17
Copy link
Contributor

@lan17 lan17 commented Mar 12, 2026 •
edited
Loading

corresponding docs update: agentcontrol/docs-agent-control#28

Summary

  • replace flat control predicates with recursive condition trees across the shared models, engine, server, SDKs, and UI contracts
  • normalize legacy flat stored controls during Alembic upgrade and add safe condition_trace metadata for composite evaluation
  • regenerate the TypeScript SDK/API types for the new contract and keep rollout-time legacy read compatibility on the server/models

Scope

  • User-facing/API changes:
    • ControlDefinition now uses a top-level condition tree instead of top-level selector / evaluator
    • controls now support nested and / or / not composition with a hard API depth limit of 6
    • /api/v1 route structure stays the same, but the canonical contract is a breaking change for SDK consumers that construct control payloads directly
    • the TypeScript SDK release should be marked breaking so npm publishes a new major for the condition-tree input contract
  • Internal changes:
    • recursive engine evaluation with short-circuiting and metadata.condition_trace
    • clearer composite error traces (matched: null on error) and preserved raw diagnostics for internal observability while API responses stay sanitized
    • recursive server-side validation with nested field paths
    • Python SDK recursive leaf checks plus non-blocking server-version mismatch warnings
    • UI keeps the existing single-condition editor behavior for leaf conditions; composite trees are shown but preserved on save rather than fully edited in this PR
  • Rollout compatibility notes:
    • server/models still canonicalize legacy flat control payloads (selector + evaluator) into condition during rollout
    • legacy flat rows in the database are normalized by Alembic revision 9f2f5a4e6c1b_normalize_legacy_control_conditions
    • the standalone migration script/Make target was removed; Alembic is the one authoritative migration path
  • Out of scope:
    • full condition-tree editing in the current UI modal
    • runtime strict rejection of legacy flat control payloads
    • drag-and-drop tree editing

Risk and Rollout

  • Risk level: high
  • Rollback plan:
    • take a database backup before running alembic upgrade head
    • if rollout fails before the Alembic data migration runs, revert to the previous server/SDK major
    • if rollout fails after the Alembic data migration runs, restore the pre-migration database snapshot before rolling back the server major
  • Migration behavior:
    • the Alembic normalization is SQL-only and runs once during upgrade
    • it fails hard if stored control rows are ambiguous/corrupted (mixed canonical+legacy fields, partial legacy fields, non-object JSON, etc.)
    • the migration is intentionally irreversible

Testing

  • Added or updated automated tests
  • Ran make check
  • Manually verified behavior

make check passed, which covered:

  • make models-test
  • make server-test
  • make engine-test
  • make sdk-test
  • make evaluators-test
  • repo linting
  • repo typechecking

Additional focused coverage added in this PR includes:

  • direct model tests for recursive condition trees and legacy canonicalization
  • engine tests for composite traversal, short-circuiting, traces, and composite error handling
  • server validation/error-path tests for nested field paths and sanitized evaluator failures
  • compatibility tests for legacy flat stored control payloads on read
  • dedicated Alembic migration tests covering no-op, rewrite, invalid-row failure, atomic rollback, offline rejection, API post-migration shape, and multi-row rewrite
  • UI tests for the current composite-editing limitation and JSON editor behavior

Notes:

  • the full check run emitted a few existing third-party warnings (sqlglot[rs] deprecation, Strands resource/deprecation warnings), but the targets passed cleanly

Checklist

  • Linked issue/spec: sc-57582, sc-58429
  • Updated docs/examples for user-facing changes
  • Included any required follow-up tasks

lan17 added 2 commits March 11, 2026 22:03
@lan17
feat!: implement recursive control condition trees
6465572
@lan17
Merge remote-tracking branch 'origin/main' into codex/feature/sc-5842…
46bee1d 
…9-condition-trees

# Conflicts:
#	ui/src/core/page-components/agent-detail/modals/edit-control/edit-control-content.tsx
@lan17 lan17 changed the title feat!: implement recursive control condition trees feat(server)!: implement recursive control condition trees Mar 12, 2026
@codecov
Copy link

codecov bot commented Mar 12, 2026 •
edited
Loading

Codecov Report

❌ Patch coverage is 94.10569% with 29 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
models/src/agent_control_models/controls.py 91.85% 11 Missing ⚠️
engine/src/agent_control_engine/core.py 93.27% 8 Missing ⚠️
...ver/src/agent_control_server/endpoints/controls.py 91.66% 5 Missing ⚠️
...erver/src/agent_control_server/endpoints/agents.py 92.00% 4 Missing ⚠️
...ent_control_server/services/control_definitions.py 96.00% 1 Missing ⚠️

📢 Thoughts on this report? Let us know!

@lan17 lan17 marked this pull request as ready for review March 12, 2026 21:16
This was referenced Mar 12, 2026
Merged
Closed
@namrataghadi-galileo
Copy link
Contributor

namrataghadi-galileo commented Mar 13, 2026 

flowchart TD
  C["condition (root)"] --> A["and"]
  C --> O["or"]
  C --> N["not"]

  A --> L1["leaf: selector + evaluator"]
  A --> L2["leaf: selector + evaluator"]

  O --> L3["leaf: selector + evaluator"]
  O --> A2["and"]
  A2 --> L4["leaf: selector + evaluator"]
  A2 --> L5["leaf: selector + evaluator"]

  N --> L6["leaf: selector + evaluator"]
Loading

namrataghadi-galileo
namrataghadi-galileo requested changes Mar 13, 2026
View reviewed changes
@namrataghadi-galileo
Copy link
Contributor

namrataghadi-galileo commented Mar 13, 2026

One suggestion from Observability perspective:

Current issue:
- primary_leaf() returns None for composite conditions, so evaluator_name and selector_path become null in observability events.

Suggested change:
- Don’t use primary_leaf() for observability identity.
- Derive a deterministic representative from all leaves (first leaf in traversal order).
- Keep full composite context in metadata.

Proposed behavior:
- evaluator_name = first leaf evaluator
- selector_path = first leaf selector path
- add metadata:
leaf_count
all_evaluators (ordered, deduped)
all_selector_paths (ordered, deduped)
optionally representative_* naming to avoid semantic confusion

Why:
- Prevents null observability dimensions for composite controls.
- Preserves backward compatibility for dashboards filtering by evaluator/selector.
- Still keeps full truth about all leaves in metadata.

@lan17
Copy link
Contributor Author

lan17 commented Mar 14, 2026

Following up on the broader observability note: I aligned server and SDK event emission so composite conditions use a deterministic representative leaf for top-level selector_path / evaluator_name, while preserving the full composite context in metadata (primary_*, leaf_count, ordered/deduped evaluator and selector lists).

namrataghadi-galileo
namrataghadi-galileo reviewed Mar 16, 2026
View reviewed changes
@lan17 lan17 merged commit 2ff4c12 into main Mar 17, 2026
7 checks passed
@lan17 lan17 deleted the codex/feature/sc-58429-condition-trees branch March 17, 2026 23:40
galileo-automation pushed a commit that referenced this pull request Mar 18, 2026
@semantic-release-bot
chore(release): ts sdk v2.0.0 [skip ci]
8b6e3f5 
## [2.0.0](ts-sdk-v1.1.0...ts-sdk-v2.0.0) (2026-03-18)

### ⚠ BREAKING CHANGES

* **server:** implement recursive control condition trees (#115)

### Features

* **docs:** simplify main README quick start v2 ([#100](#100)) ([7701c65](7701c65))
* **docs:** Update README.md to accurately mention Strands Agents SDK ([#105](#105)) ([84dfa57](84dfa57))
* **evaluators:** add Cisco AI Defense evaluator and examples ([#60](#60)) ([52e2416](52e2416))
* **sdk:** add Google ADK framework integration ([#83](#83)) ([f2b53ee](f2b53ee))
* **server:** implement recursive control condition trees ([#115](#115)) ([2ff4c12](2ff4c12))

### Bug Fixes

* **docs:** clarify README quickstart flow ([#119](#119)) ([317c626](317c626))
* **docs:** cleanup readme ([#66](#66)) ([eca0d6b](eca0d6b))
* **docs:** promote Google ADK plugin in README ([#99](#99)) ([f038aa4](f038aa4))
* **evaluators:** address Cisco AI Defense review issues ([#103](#103)) ([81da81b](81da81b))
* **examples:** shut down SDK in short-lived demos ([#85](#85)) ([df43264](df43264))
* **sdk:** fail closed on post-hook evaluation errors ([#114](#114)) ([67f8fc1](67f8fc1)), closes [#112](#112)
* **sdk:** skip evaluation when no controls apply ([#124](#124)) ([d2cd9f9](d2cd9f9))
* **server:** escape ILIKE pattern in evaluator-configs list endpoint ([#108](#108)) ([cb6e89f](cb6e89f))
* **server:** reject empty string list evaluator values ([#121](#121)) ([2c55d27](2c55d27))
* **server:** revert unwanted changes in server config ([#117](#117)) ([d92e168](d92e168))
* **ui:** create flow - name trimming issue ([#93](#93)) ([1a9759d](1a9759d))
@galileo-automation
Copy link
Collaborator

galileo-automation commented Mar 18, 2026

🎉 This PR is included in version 2.0.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@yashsheth46 yashsheth46 yashsheth46 approved these changes

@namrataghadi-galileo namrataghadi-galileo namrataghadi-galileo approved these changes

@abhinav-galileo abhinav-galileo Awaiting requested review from abhinav-galileo

Assignees

No one assigned

Labels

released

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@lan17 @namrataghadi-galileo @galileo-automation @yashsheth46